ShowTable of Contents
概要
フォームでは、表示した文書の保存のタイミングで、入力チェックや他の文書への処理などを行っている例は少なくない。
このような場合、LotusScriptを使ってエージェントやスクリプトライブラリに処理を記述している。
ここでは、そのような既存のソースを有効活用する または、使いなれたLotusScriptをできるだけ利用する為に
LotusScriptで記述されたエージェントを呼び出す方法について記述する。
実現方法
agentクラスのrunWithDocumentContext関数を利用して実現できる。
以下、２通りの方法がある。
実現方法 | 詳細 |
| ①保存した文書をエージェントに渡す方法 | xPage上でバインディングされた文書内の値を利用してエージェントを呼び出す場合に有効。
ただし、一旦文書の保存が必要。
|
| ②文書を保存せずにエージェントに渡す方法 | ダミー用にcreateされた文書へxPage上の値を渡し、エージェントを呼び出す。文書を保存したくない場合に有効。 |
◆補足
agentクラスのrun関数にて文書のNoteIDを渡す方法もあるが、ここでは説明対象外とする。
エージェントの準備
呼び出すエージェントとして既存のエージェントをそのまま利用した場合、
サーバーサイドでの処理の為、MessageBoxが表示されないなど何点か不具合が生じる。
不具合解消のためには、事前にエージェントを修正しておく必要がある。
エージェントを使用せず、直接スクリプトライブラリに作成した関数を使用していた場合は、呼び出す為のエージェントを作成する必要がある。
1.既存エージェントの修正
エージェントの処理内容や作り方によって異なってくるが、以下の内容をポイントに見直し修正する。
◆修正ポイントと詳細
修正のポイント | 詳細 |
UIに表示されたdocumentを取得 | runWithDocumentContextにてエージェントに引き渡されたdocumentを取得する為にエージェント冒頭でNotesSessionクラスのDocumentContextプロパティを使用する必要がある。
Set doc = session.DocumentContext |
| エラーハンドリング対策 | MessageBoxの代わりにエラー内容(または、エラーキー）をdocumentに埋め込む。
戻ってきたエラー内容をクライアントサイドで画面上に表示するなどのハンドリングを行う。
|
◆エージェントの修正例
項目 | ①保存した文書をエージェントに渡す場合 | ②文書を保存せずにエージェントに渡す場合 |
| 修正内容 | 【UIに表示されたdocumentを取得】
UIの値を一旦保存することで、アイテムをxPage上でバインディングされた文書内の値から取得する。
【エラーハンドリング対策】
エラーハンドリングを行い、エラー内容をDocumentに埋め込む。 | 【UIに表示されたdocumentを取得】
UIの値をダミー文書を介して取得する。
【エラーハンドリング対策】
エラーハンドリングを行い、エラーキーをダミー文書を介して返す。 |
| 修正例 | Sub Initialize
Dim session As New NotesSession
Dim doc As NotesDocument
Dim lByteLen As Long
Dim lCharLen As Long
Dim sErrCD As String
'保存された文書を取得する。
Set doc = session.DocumentContext
'入力チェック
'未入力
If Len(Trim$(doc.Getitemvalue("Text")(0))) = 0 Then
sErrCD = "ERR1"
GoTo Err_Handle
End If
'半?チェック
' チェック文字列のバイト数を取得
lByteLen = LenBP(Trim$(doc.Getitemvalue("Text")(0)))
' チェック文字列の桁数を取得
lCharLen = Len(Trim$(doc.Getitemvalue("Text")(0)))
If lByteLen <> lCharLen Then
sErrCD = "ERR2"
GoTo Err_Handle
End If
Call doc.ReplaceItemValue("Out_Text", "")
Call doc.Save(True, False)
Exit Sub
Err_Handle:
Select Case sErrCD
Case "ERR1"
Call doc.ReplaceItemValue("Out_Text", "テキスト内容を入力してください。")
Case "ERR2"
Call doc.ReplaceItemValue("Out_Text", "半角で入力してください。")
End Select
Call doc.Save(True, False)
End Sub | Sub Initialize
Dim session As New NotesSession
Dim doc As NotesDocument
Dim item As NotesItem
Dim lByteLen As Long
Dim lCharLen As Long
'UIの画面項目を取得する。
Set doc = session.DocumentContext
'入力チェック
'未入力
If Len(Trim$(doc.Getitemvalue("Input")(0))) = 0 Then
Set item = doc.AppendItemValue("Output","ERR1")
End If
'半角チェック
' チェック文字列のバイト数を取得
lByteLen = LenBP(Trim$(doc.Getitemvalue("Input")(0)))
' チェック文字列の桁数を取得
lCharLen = Len(Trim$(doc.Getitemvalue("Input")(0)))
If lByteLen <> lCharLen Then
Set item = doc.AppendItemValue("Output","ERR2")
End If
End Sub |
2.エージェントのプロパティ設定
エージェントをWebで実行できるようにするには、以下の設定が必要となる。
（この設定は、文書の保存の有無に関わらず、共通）
2-1.[プロパティ]-[基本]-[名前]にエージェント名に該当する「名前」を入力し、実行時オプションの対象を「なし」にする。
2-2.[プロパティ]-[セキュリティー]を選択し、「Webユーザーとして実行」にチェックを入れる。
Xpageからのエージェントの呼び出し
Xpageからのエージェントの呼び出しは、「①保存した文書をエージェントに渡す場合」と、「②文書を保存せずにエージェントに渡す場合」で手順が異なる。
①保存した文書をエージェントに渡す場合
1.Xpageの作成
新規Xpageを作成し、入力チェックを行うフィールドとチェックの結果を表示するフィールド、エージェントを呼び出すボタンを作成する。
◆補足
データソースとなるフォーム、フィールドはあらかじめ作成しておく。
1-1.新規にXPageを作成。
1-2.Xpageにフィールドを配置する。
1-3.フィールドに定義したデータソースをバインディングする。
◆補足
プロパティタブでの設定も可能。
2-1.イベントタブのonclickでアクションを追加する。
2-2.保存した文書を渡すため、最初に文書を保存する。
◆補足
あらかじめ文書が保存されている場合は不要。
2-3.エージェントを呼び出すための記述を記載する。
◆JavaScriptの詳細内容
保存した文書を処理する場合 | 補足説明 |
var agent = database.getAgent("Test2Agent");
//保存されたデータソースを定義する。
var doc = Test2.getDocument();
//エージェント実行に現在の保存されたデータソースを渡す。
agent.runWithDocumentContext(doc);
agent.recycle();
context.reloadPage();
| 呼び出すエージェントを定義
>フィールドの値をセットするデータソースを定義
>Xpageからエージェント呼び出す。引数にデータソースを渡す。
>オブジェクトを破棄し、メモリをシステムに返す。
>サーバースクリプトを実行しているコンテキストを再ロードする。 |
②文書を保存せずにエージェントに渡す場合
1.Xpageの作成
新規Xpageの作成は、「①-1.Xpageの作成」と同様。
ただし、データのバインディングは不要。
2.エージェントの呼び出し
2-1.イベントタブのonclickでアクションを追加する。
2-2.エージェントを呼び出すための記述を記載します。
◆JavaScriptの詳細内容
処理内容 | 補足説明 |
var agent = database.getAgent("Test2Agent");
var compInput = getComponent("Text");
var compOutput:com.ibm.xsp.component.xp.XspInputText = getComponent("Out_Text");
//エージェント実行に必要な情報をDocに保持して渡す。
var doc = database.createDocument();
//入力した値を取得し、Docに保持する。
var paramIn = compInput.getValue();
doc.appendItemValue("Input",paramIn);
//エージェント起動
agent.runWithDocumentContext(doc);
//エージェントからの戻りでエラーハンドリング
if (doc.getItemValueString("Output") == ""){
compOutput.setValueFromString("OK");
}else{
if (doc.getItemValueString("Output") == "ERR1"){
compOutput.setValueFromString("テキスト内容を入力してください。");
}else{
compOutput.setValueFromString("半角で入力してください。");
}
}
//エージェントに引き渡すために作成したDocを破棄する。
doc.recycle();
agent.recycle();
| 呼び出すエージェントを定義
>入力チェックを行うフィールドから値を取得
>入力チェックの結果を表示するフィールドの定義
(UIに直接テキストをセットする型を定義)
>エージェントに渡すダミー文書を作成する。
>入力チェックを行う値をダミー文書に追加する。
>ダミー文書から結果を取得しエラーハンドリングする。
>入力チェックの結果がエラーの時、エラー文言を表示 |
エージェントの実行
エージェントを実行すると、以下のように動作する。
(実行前)
(実行後）
(実行前)
(実行後）
まとめ
既存のエージェントやスクリプトライブラリを再利用して、xPagesから処理を行いたいといったケースは多々あると想定される。
そのような場合、上記のように多少の改訂は必要なものの、UIの処理目的に応じて対応することは可能になる。
参考サイト
調査環境
Lotus Domino Designer 8.5.3 Upgrade Pack1
Internet Explorer 8
Google Chrome 19.0.1084.46 m
Mozilla Firefox 12
Safari 5.1.5
この記事は九州地区ノーツパートナー会技術部会(リコー IT ソリューションズ 株式会社)によって作成されました。